Purpose
The localeCompare task is used to compare two strings in the current locale and returns a numeric value (negative, 0, positive) indicating whether the reference string comes before, after, or is the same as the compareString in sort order. The locale is based on the language settings of the browser.
Potential Use Case
Use this task to sort an array of strings with special characters, or when you need to implement "natural sorting" in which numbers are treated as numbers (sorted from low to high), even when they are embeded within a string. This task method also provides multiple options to control how certain formatting conventions are handled when sorting.
Properties
Input and output properties are shown below.
| Input | Type | Required | Description |
|---|---|---|---|
referenceStr |
String | Yes | The reference string to compare. |
compareString |
String | Yes | The string to compare against the referenceStr. |
locales |
String | No | A string that holds a BCP 47 language tag, or an array of such language tags. If the locales parameter is not provided, the default locale is used. The following Unicode extension keys are also allowed: \"co\", \"kn\", \"kf\". |
options |
Object | No | The options to apply to the sort order. The options object has some or all of the following properties: \"caseFirst\" \"ignorePunctuation\" \"localeMatcher\" \"numeric\" \"sensitivity\" \"usage\" |
| Output | Type | Description |
|---|---|---|
compareResult |
Number | A number that indicates if the reference string is lower, equal or greater than the comparison string, according to the locale. Returns one of three values: -1 (negative) when the reference string appears before compareString 0 if the two strings are equal and appear at the same position in the sort order 1 (positive) when the reference string appears after compareString Note: Do not rely on exact return values of -1 or 1. Negative and positive number results vary between browsers and browser versions. |
Examples
Example 1
In this example, the incoming referenceStr is "Hello World" and the compareString is "héllö wôrld". Note the accute accent "é" and diaeresis "o" in "héllö", and the circumflex "ô" in "wôrld".
The compareResult for this example returns -1 (negative) because the reference string comes before the comparison string.
Example 2
In this example, the incoming referenceStr is the number "8" and the compareString is the number "30".
The compareResult for this example returns 1 (positive) because the string value "8" comes after "30" when using a string sort.
Example 3
In this example, the incoming referenceStr is "réservé" with the accute accent "é", and the compareString is "reserve". Of note, the compareString does not contain any accute accents. The locales option is statically set to use the "en" (English) language tag. A "sensitivity: base" option was applied in the options variable to indicate the strings do not have the same base letters.
The compareResult for this example returns 0 because the two strings are considered equal.
Additional Information
See the Intl.Collator constructor page on the MDN developer site for more information on how to use thelocales and options parameters.